Banner

warning

This is the documentation for the Advanced API. Most developers should use our Simplified API (documented in Banner), which comes with several built-in features such as:

• Automatic ad loading
• Retries for failed requests
• Simplified lifecycle management

Only use the Advanced API if you need fine-grained control over the ad loading and presentation lifecycle.

The Advanced API provides direct access to individual Banner instances, giving you complete control over when and how ads are loaded and displayed.

Create a Banner instance

Kotlin

val size = Banner.Size.Phone /* or Banner.Size.Tablet */
val banner = Banner.create(activity, "<placement-id>", size)

Java

final Banner.Size size = Banner.Size.Phone.INSTANCE; /* or Banner.Size.Tablet.INSTANCE */
final Banner banner = Banner.create(activity, "<placement-id>", size);

When creating a banner, in addition to your placementId, you have to provide:

• size: Size of the banner. See Banner sizes for the available sizes.

Register ad callbacks

Kotlin

banner.listener = object : Banner.Listener {
    override fun onPrebiddingFinished(result: PrebiddingResults) {
        Log.d("Banner", "Banner client-side bidding finished!")
    }

    override fun onLoaded(loadResult: LoadResult) {
        Log.d("Banner", "Banner loaded!")
    }

    override fun onFailedToLoad(loadError: LoadError, loadResult: LoadResult?) {
        Log.d("Banner", "Banner failed to load. Reason: ${loadError.message}")
    }

    // Impression Callback
    override fun onImpression(impressionData: ImpressionData) {
        Log.d("Banner", "Banner impression, with revenue: ${impressionData.revenue}")
    }
}

Java

banner.setListener(new Banner.Listener() {
    @Override
    public void onPrebiddingFinished(@NonNull PrebiddingResults result) {
        Log.d("Banner", "Banner client-side bidding finished!");
    }

    @Override
    public void onLoaded(@NonNull LoadResult loadResult) {
        Log.d("Banner", "Banner loaded!");
    }

    @Override
    public void onFailedToLoad(@NonNull LoadError loadError, @Nullable LoadResult loadResult) {
        Log.d("Banner", "Banner failed to load. Reason: " + loadError.getMessage());
    }

    // Impression Callback
    @Override
    public void onImpression(@NonNull ImpressionData impressionData) {
        Log.d("Banner", "Banner impression, with revenue: " + impressionData.getRevenue());
    }

    @Override
    public void onClicked() { }

    @Override
    public void onNetworkImpression(@NonNull LoadResult loadResult) { }

    @Override
    public void onShowed() { }

    @Override
    public void onFailedToShow(@NonNull ShowError showError) { }

    @Override
    public void onDismissed() { }
});

Load an ad

Kotlin

banner.load()

Java

banner.load();

Load an ad (with custom properties)

Kotlin

banner.load(
    buildCustomProperties {
        addString("game_mode", "classic")
    }
)

Java

banner.load(
    new CustomProperties.Builder()
        .addString("game_mode", "classic")
        .build()
);

Displaying the banner

The most common practice is to add the banner view to the view hierarchy either:

• After creating the Banner instance.
• After the onLoaded(loadResult) listener callback is called.

Kotlin

val bannerContainer = findViewById<ViewGroup>(R.id.bannerContainer)
val bannerView = banner.view

// Optionally, set the ad space where the banner will be shown
banner.setAdSpace("banner-ad-space")

bannerContainer.addView(bannerView)

Java

ViewGroup bannerContainer = findViewById(R.id.bannerContainer);
View bannerView = banner.getView();

// Optionally, set the ad space where the banner will be shown
banner.setAdSpace("banner-ad-space");

bannerContainer.addView(bannerView);

Banner sizes

Constant	Size (WxH)	Description
Phone	320x50	Size for banners used in phone devices
Tablet	728x90	Size for banners used in tablet devices
MREC	300x250	Size for IAB Medium Rectangle banners

Size is in DP for Android.

Banner autorefresh

After being displayed for some time, our banner fires a load() call automatically to refresh its contents. You can configure this time through our Admin tool for each one of your banners.

Banner retry

Our banner has a built-in auto retry for failed load attempts. This means that when a banner fails to load, it will retry again until it loads successfully. Time between each retry attempt will increase using an exponential backoff. You should not add any retry logic on your end, as it may interfere with our retry behaviour.

Complete example

Kotlin

BannerSample.kt

import android.os.Bundle
import android.util.Log
import android.view.ViewGroup
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import com.etermax.xmediator.core.api.Banner
import com.etermax.xmediator.core.api.entities.ImpressionData
import com.etermax.xmediator.core.api.entities.LoadError
import com.etermax.xmediator.core.api.entities.LoadResult
import com.example.yourapp.R

class BannerSample : AppCompatActivity() {
    private var banner: Banner? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_banner)

        findViewById<Button>(R.id.button_load).setOnClickListener {
            Log.d("BannerSample", "Load button clicked")

            // Dispose previous banner instance
            banner?.destroy()
            findViewById<ViewGroup>(R.id.banner_container).removeAllViews()

            // Create a banner instance
            banner = Banner.create(
                activity = this,
                placementId = "<placement-id>",
                size = Banner.Size.Phone,
            )

            // Add banner to view hierarchy
            findViewById<ViewGroup>(R.id.banner_container).addView(banner?.view)

            // Setup callbacks
            banner?.listener = object : Banner.Listener {
                override fun onLoaded(loadResult: LoadResult) {
                    Log.d("BannerSample", "Loaded!")
                }

                override fun onFailedToLoad(loadError: LoadError, loadResult: LoadResult?) {
                    Log.d("BannerSample", "Failed to load. Reason: ${loadError.message}")
                }

                override fun onImpression(impressionData: ImpressionData) {
                    Log.d("BannerSample", "Impression with revenue: ${impressionData.revenue}")
                }
            }

            // Request an ad
            banner?.load()
        }
    }
}

Java

BannerSample.java

import android.os.Bundle;
import android.util.Log;
import android.view.ViewGroup;
import android.widget.Button;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.appcompat.app.AppCompatActivity;
import com.etermax.xmediator.core.api.Banner;
import com.etermax.xmediator.core.api.entities.ImpressionData;
import com.etermax.xmediator.core.api.entities.LoadError;
import com.etermax.xmediator.core.api.entities.LoadResult;
import com.example.yourapp.R;

public class BannerSample extends AppCompatActivity {
    private Banner banner = null;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_banner);

        findViewById(R.id.button_load).setOnClickListener(v -> {
            Log.d("BannerSample", "Load button clicked");

            // Dispose previous banner instance
            if (banner != null) {
                banner.destroy();
            }
            ((ViewGroup) findViewById(R.id.banner_container)).removeAllViews();

            // Create a banner instance
            banner = Banner.create(
                this,
                "<placement-id>",
                Banner.Size.Phone.INSTANCE
            );

            // Add banner to view hierarchy
            ((ViewGroup) findViewById(R.id.banner_container)).addView(banner.getView());

            // Setup callbacks
            banner.setListener(new Banner.Listener() {
                @Override
                public void onLoaded(@NonNull LoadResult loadResult) {
                    Log.d("BannerSample", "Loaded!");
                }

                @Override
                public void onFailedToLoad(@NonNull LoadError loadError, @Nullable LoadResult loadResult) {
                    Log.d("BannerSample", "Failed to load. Reason: " + loadError.getMessage());
                }

                @Override
                public void onImpression(@NonNull ImpressionData impressionData) {
                    Log.d("BannerSample", "Impression with revenue: " + impressionData.getRevenue());
                }

                @Override
                public void onClicked() { }

                @Override
                public void onNetworkImpression(@NonNull LoadResult loadResult) { }

                @Override
                public void onShowed() { }

                @Override
                public void onFailedToShow(@NonNull com.etermax.xmediator.core.api.entities.ShowError showError) { }

                @Override
                public void onDismissed() { }

                @Override
                public void onPrebiddingFinished(@NonNull com.etermax.xmediator.core.api.entities.PrebiddingResults result) { }
            });

            // Request an ad
            banner.load();
        });
    }
}